Skip to content

github: install python tools into a virtualenv - #338

Merged
jkloetzke merged 1 commit into
BobBuildTool:masterfrom
mahaase:bugfix/ci-pip-venv
Oct 25, 2026
Merged

jkloetzke merged 1 commit into
BobBuildTool:masterfrom
mahaase:bugfix/ci-pip-venv

Conversation

@mahaase

@mahaase mahaase commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor

Installing packages into the system interpreter with python -m pip install fails on runner images that enforce PEP 668:

Run python -m pip install pre-commit
error: externally-managed-environment
× This environment is externally managed
╰─> To install Python packages system-wide, try apt install
    python3-xyz, where xyz is the package you are trying to
    install.
    
    If you wish to install a non-Debian-packaged Python package,
    create a virtual environment using python3 -m venv path/to/venv.
    Then use path/to/venv/bin/python and path/to/venv/bin/pip. Make
    sure you have python3-full installed.
    
    If you wish to install a non-Debian packaged Python application,
    it may be easiest to use pipx install xyz, which will manage a
    virtual environment for you. Make sure you have pipx installed.
    
    See /usr/share/doc/python3.12/README.venv for more information.

note: If you believe this is a mistake, please contact your Python installation or OS distribution provider. You can override this, at the risk of breaking your Python installation or OS, by passing --break-system-packages.
hint: See PEP 668 for the detailed specification.
Error: Process completed with exit code 1.

This is the case for our Gitea Actions with the default gitea/runner-images:ubuntu-latest image (Ubuntu 24.04, Python 3.12). GitHub hosted runners still work because they ship a separately installed Python that is not marked as externally managed.

Create a virtualenv in $RUNNER_TEMP instead and put it into $GITHUB_PATH so that the following steps find the installed tools. This works the same on GitHub and Gitea and does not rely on the Python setup of the runner image.

Maybe this is generic and will work for github too... and maybe using a newer image on github will also raise this issue?

Installing packages into the system interpreter with "python -m pip
install" fails on runner images that enforce PEP 668:

    error: externally-managed-environment

This is the case for Gitea Actions with the default
gitea/runner-images:ubuntu-latest image (Ubuntu 24.04, Python 3.12).
GitHub hosted runners still work because they ship a separately
installed Python that is not marked as externally managed.

Create a virtualenv in $RUNNER_TEMP instead and put it into $GITHUB_PATH
so that the following steps find the installed tools. This works the
same on GitHub and Gitea and does not rely on the Python setup of the
runner image.
@jkloetzke

Copy link
Copy Markdown
Member

Thanks. Seems to work for Github as well.

@jkloetzke
jkloetzke merged commit 1481ef4 into BobBuildTool:master Oct 25, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants